Node / meshtastic / Meshtastic-Android / files / docs / assets / screenshots / README.md

Displaying Raw • View rendered • Download

Tc9d1d9# Screenshots

This directory is the **single source of truth** for screenshot assets referenced by the

documentation pages. It is consumed by both:

Tff7b72- the **Jekyll docs site** (markdown references Ta5d6ff`../../assets/screenshots/{name}.png`), and

Tff7b72- the **in-app docs browser** — Ta5d6ff`:feature:docs:syncDocsToComposeResources` bundles this

directory into compose resources at Ta5d6ff`files/docs/assets/screenshots/`.

Ta5d6ff`DocImageWiringTest` (in Ta5d6ff`:feature:docs`) fails the build if a doc page references an image

that is not present here.

Tc9d1d9## Two source modules

Doc screenshots come from Compose Preview Screenshot Testing references in **two** modules:

Tff7b72- **`:screenshot-tests`** — visual-regression gate (CI runs Ta5d6ff`:screenshot-tests:validateDebugScreenshotTest`).

Holds atomic, dual-purpose components (signal/battery/hops info, list items, preference widgets,

alerts) that are both regression-checked **and** used as doc images. Don't reframe these for docs.

Tff7b72- **`:docs-screenshots`** — generate-only, **not** gated in CI. Holds doc-framed compositions whose

framing is tuned for the docs site (e.g. the firmware status crops, the connections BLE-scan /

empty-state crops). Reframing one here never churns the regression gate.

Ta5d6ff`copyDocsScreenshots` (in Ta5d6ff`:screenshot-tests`) aggregates the reference images from **both** modules.

Tc9d1d9## Updating Screenshots

After changing a UI component, regenerate references for whichever module owns the wrapper, then copy:

Ta5d6ff```Ta5d6ffbash

./gradlew :screenshot-tests:updateDebugScreenshotTest T8b949e# regression references

./gradlew :docs-screenshots:updateDebugScreenshotTest T8b949e# doc-framed composition references

./gradlew :screenshot-tests:copyDocsScreenshots T8b949e# refresh this directory from both

Ta5d6ff```

Ta5d6ff`copyDocsScreenshots` copies **only** the light-mode reference images that have a semantic

alias in Ta5d6ff`screenshot-tests/docs-screenshot-aliases.properties`, renaming them on the way.

Commit the refreshed PNGs together with the reference-image changes.

Tc9d1d9## Adding a Screenshot for a New Doc Page

Tff7b721. Add (or reuse) a Ta5d6ff`Preview*`/Ta5d6ff`*Preview` composable with representative mock data in the

feature module. Add a Ta5d6ff`Screenshot*` wrapper: in **`:docs-screenshots`** if it's a doc-framed

composition (full screen / doc-specific crop), or in **`:screenshot-tests`** if it's an atomic

component you also want regression-gated. If the component renders timestamps, give it a

Ta5d6ff`timeTextOverride`-style parameter so renders stay deterministic across machines.

Tff7b722. Make sure the test class is covered by a pattern in Ta5d6ff`screenshot-tests/docs-screenshots-manifest.txt`

(the patterns are Ta5d6ff`**/{Class}Kt/...`, so they match in either module).

Tff7b723. Map the semantic name in Ta5d6ff`screenshot-tests/docs-screenshot-aliases.properties`:

Ta5d6ff`{page-id}_{description}.png=Screenshot{Name}_Light_{hash}_0.png`

Tff7b724. Run the relevant update task(s) + Ta5d6ff`copyDocsScreenshots`, then reference the image from the doc page.

Tc9d1d9## Naming Convention

Ta5d6ff```

{page-id}_{description}.png

```

Examples: Ta5d6ff`onboarding_welcome.png`, Ta5d6ff`connections_bluetooth_scan.png`, Ta5d6ff`discovery_preset_result.png`.

Tc9d1d9## Guidelines

Tff7b72- PNG format, light-mode only (dark variants live in the reference directory)

Tff7b72- Name screenshots to match the docs page they appear in

Tff7b72- Keep filenames lowercase with underscores

Tff7b72- Prefer CST-generated screenshots — they render real app composables, so they cannot drift from

reality. Avoid hand-pasted captures: a stray screenshot from another app slipped in this way

before (the old Ta5d6ff`connections_wifi_*.png` were from an unrelated WiFi-provisioning app, not

Meshtastic). If a manual capture is unavoidable, it must be a genuine Meshtastic-Android screen.